<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="prev" href="typesseq-xrange.html" />
<link rel="parent" href="typesseq.html" />
<link rel="next" href="types-set.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>3.6.4 Mutable Sequence Types </title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="3.6.3 xrange Type"
  href="typesseq-xrange.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="3.6 sequence Types "
  href="typesseq.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="3.7 set Types "
  href="types-set.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="typesseq-xrange.html">3.6.3 XRange Type</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="typesseq.html">3.6 Sequence Types </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="types-set.html">3.7 Set Types </a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h2><a name="SECTION005640000000000000000"></a><a name="typesseq-mutable"></a>
<br>
3.6.4 Mutable Sequence Types 
</h2>

<p>
List objects support additional operations that allow in-place
modification of the object.
Other mutable sequence types (when added to the language) should
also support these operations.
Strings and tuples are immutable sequence types: such objects cannot
be modified once created.
The following operations are defined on mutable sequence types (where
<var>x</var> is an arbitrary object):
<a id='l2h-275' xml:id='l2h-275'></a><a id='l2h-276' xml:id='l2h-276'></a>
<p>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="center">Operation</th>
      <th class="left"  >Result</th>
      <th class="center">Notes</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="center" valign="baseline"><code><var>s</var>[<var>i</var>] = <var>x</var></code></td>
        <td class="left"  >item <var>i</var> of <var>s</var> is replaced by <var>x</var></td>
        <td class="center"></td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>[<var>i</var>:<var>j</var>] = <var>t</var></code></td>
        <td class="left"  >slice of <var>s</var> from <var>i</var> to <var>j</var> 
         is replaced by the contents of the iterable <var>t</var></td>
        <td class="center"></td></tr>
    <tr><td class="center" valign="baseline"><code>del <var>s</var>[<var>i</var>:<var>j</var>]</code></td>
        <td class="left"  >same as <code><var>s</var>[<var>i</var>:<var>j</var>] = []</code></td>
        <td class="center"></td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>[<var>i</var>:<var>j</var>:<var>k</var>] = <var>t</var></code></td>
        <td class="left"  >the elements of <code><var>s</var>[<var>i</var>:<var>j</var>:<var>k</var>]</code> are replaced by those of <var>t</var></td>
        <td class="center">(1)</td></tr>
    <tr><td class="center" valign="baseline"><code>del <var>s</var>[<var>i</var>:<var>j</var>:<var>k</var>]</code></td>
        <td class="left"  >removes the elements of <code><var>s</var>[<var>i</var>:<var>j</var>:<var>k</var>]</code> from the list</td>
        <td class="center"></td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.append(<var>x</var>)</code></td>
        <td class="left"  >same as <code><var>s</var>[len(<var>s</var>):len(<var>s</var>)] = [<var>x</var>]</code></td>
        <td class="center">(2)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.extend(<var>x</var>)</code></td>
        <td class="left"  >same as <code><var>s</var>[len(<var>s</var>):len(<var>s</var>)] = <var>x</var></code></td>
        <td class="center">(3)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.count(<var>x</var>)</code></td>
        <td class="left"  >return number of <var>i</var>'s for which <code><var>s</var>[<var>i</var>] == <var>x</var></code></td>
        <td class="center"></td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.index(<var>x</var><big>[</big>, <var>i</var><big>[</big>, <var>j</var><big>]</big><big>]</big>)</code></td>
        <td class="left"  >return smallest <var>k</var> such that <code><var>s</var>[<var>k</var>] == <var>x</var></code> and
    <code><var>i</var> &lt;= <var>k</var> &lt; <var>j</var></code></td>
        <td class="center">(4)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.insert(<var>i</var>, <var>x</var>)</code></td>
        <td class="left"  >same as <code><var>s</var>[<var>i</var>:<var>i</var>] = [<var>x</var>]</code></td>
        <td class="center">(5)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.pop(<big>[</big><var>i</var><big>]</big>)</code></td>
        <td class="left"  >same as <code><var>x</var> = <var>s</var>[<var>i</var>]; del <var>s</var>[<var>i</var>]; return <var>x</var></code></td>
        <td class="center">(6)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.remove(<var>x</var>)</code></td>
        <td class="left"  >same as <code>del <var>s</var>[<var>s</var>.index(<var>x</var>)]</code></td>
        <td class="center">(4)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.reverse()</code></td>
        <td class="left"  >reverses the items of <var>s</var> in place</td>
        <td class="center">(7)</td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.sort(<big>[</big><var>cmp</var><big>[</big>,
                        <var>key</var><big>[</big>, <var>reverse</var><big>]</big><big>]</big><big>]</big>)</code></td>
        <td class="left"  >sort the items of <var>s</var> in place</td>
        <td class="center">(7), (8), (9), (10)</td></tr></tbody>
</table></div>
<a id='l2h-277' xml:id='l2h-277'></a><a id='l2h-278' xml:id='l2h-278'></a><a id='l2h-279' xml:id='l2h-279'></a><a id='l2h-280' xml:id='l2h-280'></a><a id='l2h-281' xml:id='l2h-281'></a><a id='l2h-282' xml:id='l2h-282'></a><a id='l2h-283' xml:id='l2h-283'></a><a id='l2h-285' xml:id='l2h-285'></a>
Notes:
<dl>
<dt><strong>(1)</strong></dt>
<dd><var>t</var> must have the same length as the slice it is 
  replacing.

<p>
</dd>
<dt><strong>(2)</strong></dt>
<dd>The C implementation of Python has historically accepted
  multiple parameters and implicitly joined them into a tuple; this
  no longer works in Python 2.0.  Use of this misfeature has been
  deprecated since Python 1.4.

<p>
</dd>
<dt><strong>(3)</strong></dt>
<dd><var>x</var> can be any iterable object.

<p>
</dd>
<dt><strong>(4)</strong></dt>
<dd>Raises <tt class="exception">ValueError</tt> when <var>x</var> is not found in
  <var>s</var>. When a negative index is passed as the second or third parameter
  to the <tt class="method">index()</tt> method, the list length is added, as for slice
  indices.  If it is still negative, it is truncated to zero, as for
  slice indices.  
<span class="versionnote">Changed in version 2.3:
Previously, <tt class="method">index()</tt> didn't
  have arguments for specifying start and stop positions.</span>

<p>
</dd>
<dt><strong>(5)</strong></dt>
<dd>When a negative index is passed as the first parameter to
  the <tt class="method">insert()</tt> method, the list length is added, as for slice
  indices.  If it is still negative, it is truncated to zero, as for
  slice indices.  
<span class="versionnote">Changed in version 2.3:
Previously, all negative indices
  were truncated to zero.</span>

<p>
</dd>
<dt><strong>(6)</strong></dt>
<dd>The <tt class="method">pop()</tt> method is only supported by the list and
  array types.  The optional argument <var>i</var> defaults to <code>-1</code>,
  so that by default the last item is removed and returned.

<p>
</dd>
<dt><strong>(7)</strong></dt>
<dd>The <tt class="method">sort()</tt> and <tt class="method">reverse()</tt> methods modify the
  list in place for economy of space when sorting or reversing a large
  list.  To remind you that they operate by side effect, they don't return
  the sorted or reversed list.

<p>
</dd>
<dt><strong>(8)</strong></dt>
<dd>The <tt class="method">sort()</tt> method takes optional arguments for
  controlling the comparisons.

<p>
<var>cmp</var> specifies a custom comparison function of two arguments
     (list items) which should return a negative, zero or positive number
     depending on whether the first argument is considered smaller than,
     equal to, or larger than the second argument:
     "<tt class="samp"><var>cmp</var>=<tt class="keyword">lambda</tt> <var>x</var>,<var>y</var>:
     <tt class="function">cmp</tt>(x.lower(), y.lower())</tt>"
<p>
<var>key</var> specifies a function of one argument that is used to
     extract a comparison key from each list element:
     "<tt class="samp"><var>key</var>=<tt class="function">str.lower</tt></tt>"
<p>
<var>reverse</var> is a boolean value.  If set to <code>True</code>, then the
     list elements are sorted as if each comparison were reversed.

<p>
In general, the <var>key</var> and <var>reverse</var> conversion processes are
  much faster than specifying an equivalent <var>cmp</var> function.  This is
  because <var>cmp</var> is called multiple times for each list element while
  <var>key</var> and <var>reverse</var> touch each element only once.

<p>

<span class="versionnote">Changed in version 2.3:
Support for <code>None</code> as an equivalent to omitting
  <var>cmp</var> was added.</span>

<p>

<span class="versionnote">Changed in version 2.4:
Support for <var>key</var> and <var>reverse</var> was added.</span>

<p>
</dd>
<dt><strong>(9)</strong></dt>
<dd>Starting with Python 2.3, the <tt class="method">sort()</tt> method is
  guaranteed to be stable.  A sort is stable if it guarantees not to
  change the relative order of elements that compare equal -- this is
  helpful for sorting in multiple passes (for example, sort by
  department, then by salary grade).

<p>
</dd>
<dt><strong>(10)</strong></dt>
<dd>While a list is being sorted, the effect of attempting to
  mutate, or even inspect, the list is undefined.  The C
  implementation of Python 2.3 and newer makes the list appear empty
  for the duration, and raises <tt class="exception">ValueError</tt> if it can detect
  that the list has been mutated during a sort.
</dd>
</dl>

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="3.6.3 xrange Type"
  href="typesseq-xrange.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="3.6 sequence Types "
  href="typesseq.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="3.7 set Types "
  href="types-set.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="typesseq-xrange.html">3.6.3 XRange Type</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="typesseq.html">3.6 Sequence Types </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="types-set.html">3.7 Set Types </a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
